docs: voice audit — rewrite AI-written documentation in John's voice by ehrlinger · Pull Request #92 · ehrlinger/ggRandomForests

ehrlinger · 2026-05-22T15:33:41Z

Summary

Rewrites the AI-written documentation across ggRandomForests so the package reads in one consistent human voice. Voice-only: no factual or content changes. Function signatures, argument names, return-value facts, example code, version numbers, and issue references are unchanged.

Covers roxygen (varPro family, gg_brier, ROC/randomForest surface, gg_partial family, S3 methods), the three vignettes, README, and the v2.8.0 NEWS entries. Mixed files had only their 2026-era AI prose rewritten; original JSS-era prose was left untouched.

Adds dev/voice-fingerprint.md (the two-register voice reference, synced from the author's vault) and dev/voice-audit-classification.md (records what was and was not in scope). Design spec and implementation plan are in dev/plans/.

Test plan

devtools::check(args = "--as-cran") — 0 errors, 0 warnings, 0 notes
All 3 vignettes render
devtools::test() — 0 failures
Em-dash density: added <= removed
Diff is documentation-only (roxygen/man/vignettes/README/NEWS/dev), no code or test changes

Plan to audit all ggRandomForests docs (roxygen, vignettes, README, NEWS) and rewrite AI-written portions in John's voice. Approach: build a two- register voice fingerprint from JSS-era prose + supplied writing samples, classify every doc surface, rewrite only the AI/mixed surfaces. Voice-only: no factual/content changes. Ships as one PR before the v2.8.0 RC.

Per review: add 'don't overstate' rule, log ellipses as informal-register habit, and distinguish mechanical parallelism (an AI tell) from pedagogical repetition (kept — it is the voice).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

print_helpers.R, ribbon_style.R, utils.R carry zero roxygen lines and produce no man pages; they are out of scope for a documentation voice audit. Earlier pass over-classified them as AI/rewrite.

…ation audit

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

codecov · 2026-05-22T15:37:30Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.31%. Comparing base (49e4c2f) to head (01d6d16).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #92   +/-   ##
=======================================
  Coverage   87.31%   87.31%           
=======================================
  Files          38       38           
  Lines        3098     3098           
=======================================
  Hits         2705     2705           
  Misses        393      393

Files with missing lines	Coverage Δ
R/autoplot_methods.R	`85.71% <ø> (ø)`
R/gg_brier.R	`89.33% <ø> (ø)`
R/gg_partial_rfsrc.R	`89.68% <ø> (ø)`
R/gg_partial_varpro.R	`95.23% <ø> (ø)`
R/gg_partialpro.R	`100.00% <ø> (ø)`
R/gg_roc.R	`87.71% <ø> (ø)`
R/gg_udependent.R	`88.79% <ø> (ø)`
R/gg_variable.R	`85.41% <ø> (ø)`
R/gg_varpro.R	`100.00% <ø> (ø)`
R/plot.gg_brier.R	`100.00% <ø> (ø)`
... and 9 more

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull request overview

This PR standardizes the documentation voice across ggRandomForests so that newer AI-era prose reads in a consistent “John” narrative/terse register, while keeping code, signatures, examples, and references unchanged.

Changes:

Rewrites vignette / README / NEWS prose to a consistent narrative + terse voice.
Rewrites roxygen blocks for newer/mixed surfaces (varPro family, ROC/variable/partial/brier, print/summary/autoplot), regenerating matching .Rd pages.
Adds documentation-process artifacts under dev/ (voice fingerprint, classification table, design + implementation plan).

Reviewed changes

Copilot reviewed 41 out of 46 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
vignettes/ggRandomForests.qmd	Rewrite intro/explanatory prose and “Next steps” bullets in vignette voice.
vignettes/ggRandomForests-survival.qmd	Rewrite Brier/CRPS section prose and conclusion summary voice.
vignettes/ggRandomForests-regression.qmd	Rewrite select explanatory + conclusion prose voice.
README.md	Rewrite S3-method and “Why ggRandomForests?” prose for consistent voice.
NEWS.md	Rewrite v2.8.0 development bullets into the terse register.
R/varpro_feature_names.R	Roxygen wording rewrite (voice-only).
R/surv_partial.rfsrc.R	Roxygen wording rewrite (voice-only).
R/summary_methods.R	Roxygen wording rewrite (voice-only).
R/print_methods.R	Roxygen wording rewrite (voice-only).
R/autoplot_methods.R	Roxygen wording rewrite (voice-only).
R/plot.gg_varpro.R	Roxygen wording rewrite (voice-only).
R/plot.gg_variable.R	Roxygen wording rewrite (voice-only).
R/plot.gg_udependent.R	Roxygen wording rewrite (voice-only).
R/plot.gg_roc.R	Roxygen wording rewrite (voice-only).
R/plot.gg_partial_varpro.R	Roxygen wording rewrite (voice-only).
R/plot.gg_brier.R	Roxygen wording rewrite (voice-only).
R/gg_varpro.R	Roxygen wording rewrite (voice-only).
R/gg_variable.R	Roxygen wording rewrite (voice-only).
R/gg_udependent.R	Roxygen wording rewrite (voice-only).
R/gg_roc.R	Roxygen wording rewrite (voice-only).
R/gg_partialpro.R	Deprecation roxygen wording rewrite (voice-only).
R/gg_partial_varpro.R	Roxygen wording rewrite (voice-only).
R/gg_partial_rfsrc.R	Roxygen wording rewrite (voice-only).
R/gg_brier.R	Roxygen wording rewrite (voice-only).
man/varpro_feature_names.Rd	Regenerated Rd to match roxygen voice edits.
man/surv_partial.rfsrc.Rd	Regenerated Rd to match roxygen voice edits.
man/summary.gg.Rd	Regenerated Rd to match roxygen voice edits.
man/print.gg.Rd	Regenerated Rd to match roxygen voice edits.
man/plot.gg_varpro.Rd	Regenerated Rd to match roxygen voice edits.
man/plot.gg_variable.Rd	Regenerated Rd to match roxygen voice edits.
man/plot.gg_udependent.Rd	Regenerated Rd to match roxygen voice edits.
man/plot.gg_roc.Rd	Regenerated Rd to match roxygen voice edits.
man/plot.gg_partial_varpro.Rd	Regenerated Rd to match roxygen voice edits.
man/plot.gg_brier.Rd	Regenerated Rd to match roxygen voice edits.
man/gg_varpro.Rd	Regenerated Rd to match roxygen voice edits.
man/gg_variable.Rd	Regenerated Rd to match roxygen voice edits.
man/gg_udependent.Rd	Regenerated Rd to match roxygen voice edits.
man/gg_roc.rfsrc.Rd	Regenerated Rd to match roxygen voice edits.
man/gg_partial_varpro.Rd	Regenerated Rd to match roxygen voice edits.
man/gg_partial_rfsrc.Rd	Regenerated Rd to match roxygen voice edits.
man/gg_brier.Rd	Regenerated Rd to match roxygen voice edits.
man/autoplot.gg.Rd	Regenerated Rd to match roxygen voice edits.
dev/voice-fingerprint.md	Adds the two-register voice reference used as the rewrite yardstick.
dev/voice-audit-classification.md	Adds an auditable classification table for rewrite scope.
dev/plans/2026-05-22-doc-voice-audit-plan.md	Adds the implementation plan for the audit/rewrite work.
dev/plans/2026-05-22-doc-voice-audit-design.md	Adds the design spec and guardrails for voice-only changes.

Files not reviewed (5)

man/autoplot.gg.Rd: Language not supported
man/gg_brier.Rd: Language not supported
man/gg_partial_rfsrc.Rd: Language not supported
man/gg_partial_varpro.Rd: Language not supported
man/gg_roc.rfsrc.Rd: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

ehrlinger and others added 19 commits May 22, 2026 10:04

docs: refine voice fingerprint — overstatement + pedagogical repetition

717cc36

Per review: add 'don't overstate' rule, log ellipses as informal-register habit, and distinguish mechanical parallelism (an AI tell) from pedagogical repetition (kept — it is the voice).

docs: implementation plan for documentation voice audit

944a7c9

docs: add voice fingerprint (synced from vault)

781c3ca

docs: voice-audit classification table

00ccd27

docs: refine voice-audit classification for 2025-era files

ae6b0db

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs: correct classification — internal helpers have no doc surface

7b5f4f4

print_helpers.R, ribbon_style.R, utils.R carry zero roxygen lines and produce no man pages; they are out of scope for a documentation voice audit. Earlier pass over-classified them as AI/rewrite.

docs: add Task 6b (gg_partial family roxygen) — surfaced by classific…

277b148

…ation audit

docs: rewrite varPro family roxygen in John's voice

f75692e

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs: calibrate voice fingerprint — conversational, not chatty

b1d9c75

docs: dial back varPro roxygen — conversational, not chatty

8caf19d

docs: rewrite gg_brier roxygen in John's voice

7072a7a

docs: rewrite gg_partial family roxygen in John's voice

72ad2fd

docs: rewrite ROC and randomForest roxygen in John's voice

05235c9

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs: rewrite S3 method roxygen in John's voice

27779ef

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs: rewrite AI-touched vignette prose in John's voice

aa513a2

docs: rewrite README feature prose in John's voice

2a6cbca

docs: rewrite v2.8.0 NEWS entries in John's voice

be37f13

docs: trim em-dashes in NEWS and vignettes per voice fingerprint

13d2656

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

ehrlinger requested a review from Copilot May 22, 2026 15:49

Copilot started reviewing on behalf of ehrlinger May 22, 2026 15:49 View session

Copilot AI reviewed May 22, 2026

View reviewed changes

Comment thread vignettes/ggRandomForests.qmd Outdated

Comment thread README.md Outdated

Comment thread R/plot.gg_brier.R Outdated

Comment thread vignettes/ggRandomForests-survival.qmd Outdated

Comment thread vignettes/ggRandomForests-regression.qmd Outdated

Comment thread README.md Outdated

ehrlinger and others added 3 commits May 26, 2026 09:14

docs: fix factual claims flagged by Copilot review (#92)

bbcccd1

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs: fix second README claim — plot() may return patchwork too

a06101c

docs: link ggplot2 extensions gallery in README intro

01d6d16

ehrlinger merged commit 4852ab8 into main May 26, 2026
15 checks passed

ehrlinger mentioned this pull request May 26, 2026

docs: pedagogical audit of varPro wrappers (gg_partial_varpro, gg_varpro, gg_udependent) #95

Merged

2 tasks

ehrlinger deleted the docs/voice-audit-design branch May 28, 2026 14:33

ehrlinger mentioned this pull request Jun 1, 2026

docs: v3.1.0 documentation sweep + gg_vimp fix (CRAN release) #109

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: voice audit — rewrite AI-written documentation in John's voice#92

docs: voice audit — rewrite AI-written documentation in John's voice#92
ehrlinger merged 22 commits into
mainfrom
docs/voice-audit-design

ehrlinger commented May 22, 2026

Uh oh!

codecov Bot commented May 22, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

ehrlinger commented May 22, 2026

Summary

Test plan

Uh oh!

codecov Bot commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov Bot commented May 22, 2026 •

edited

Loading